SGI Freeware 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 1998 November / Freeware November 1998.img / dist / fw_elisp-manual-19.idb / usr / freeware / info / elisp-32.z / elisp-32

(.txt)

Wrap

GNU Info File | 1998-05-26 | 51KB | 958 lines

This is Info file elisp, produced by Makeinfo-1.63 from the input file elisp.texi. This version is the edition 2.4.2 of the GNU Emacs Lisp Reference Manual. It corresponds to Emacs Version 19.34. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English. File: elisp, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface Time Conversion =============== These functions convert time values (lists of two or three integers) to strings or to calendrical information. There is also a function to convert calendrical information to a time value. You can get time values from the functions `current-time' (*note Time of Day::.) and `file-attributes' (*note File Attributes::.). Many operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some operating systems have larger time values, and can represent times far in the past or future. Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number -37 represents the Gregorian year 38 B.C. - Function: format-time-string FORMAT-STRING TIME This function converts TIME to a string according to FORMAT-STRING. The argument FORMAT-STRING may contain `%'-sequences which say to substitute parts of the time. Here is a table of what the `%'-sequences mean: `%a' This stands for the abbreviated name of the day of week. `%A' This stands for the full name of the day of week. `%b' This stands for the abbreviated name of the month. `%B' This stands for the full name of the month. `%c' This is a synonym for `%x %X'. `%C' This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%A, %B %e, %Y'. `%d' This stands for the day of month, zero-padded. `%D' This is a synonym for `%m/%d/%y'. `%e' This stands for the day of month, blank-padded. `%h' This is a synonym for `%b'. `%H' This stands for the hour (00-23). `%I' This stands for the hour (00-12). `%j' This stands for the day of the year (001-366). `%k' This stands for the hour (0-23), blank padded. `%l' This stands for the hour (1-12), blank padded. `%m' This stands for the month (01-12). `%M' This stands for the minute (00-59). `%n' This stands for a newline. `%p' This stands for `AM' or `PM', as appropriate. `%r' This is a synonym for `%I:%M:%S %p'. `%R' This is a synonym for `%H:%M'. `%S' This stands for the seconds (00-60). `%t' This stands for a tab character. `%T' This is a synonym for `%H:%M:%S'. `%U' This stands for the week of the year (01-52), assuming that weeks start on Sunday. `%w' This stands for the numeric day of week (0-6). Sunday is day 0. `%W' This stands for the week of the year (01-52), assuming that weeks start on Monday. `%x' This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%D'. `%X' This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%T'. `%y' This stands for the year without century (00-99). `%Y' This stands for the year with century. `%Z' This stands for the time zone abbreviation. - Function: decode-time TIME This function converts a time value into calendrical information. The return value is a list of nine elements, as follows: (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE) Here is what the elements mean: SEC The number of seconds past the minute, as an integer between 0 and 59. MINUTE The number of minutes past the hour, as an integer between 0 and 59. HOUR The hour of the day, as an integer between 0 and 23. DAY The day of the month, as an integer between 1 and 31. MONTH The month of the year, as an integer between 1 and 12. YEAR The year, an integer typically greater than 1900. DOW The day of week, as an integer between 0 and 6, where 0 stands for Sunday. DST `t' if daylight savings time is effect, otherwise `nil'. ZONE An integer indicating the time zone, as the number of seconds east of Greenwich. Note that Common Lisp has different meanings for DOW and ZONE. - Function: encode-time SECONDS MINUTES HOUR DAY MONTH YEAR &optional ...ZONE This function is the inverse of `decode-time'. It converts seven items of calendrical data into a time value. For the meanings of the arguments, see the table above under `decode-time'. Year numbers less than 100 are treated just like other year numbers. If you want them to stand for years above 1900, you must alter them yourself before you call `encode-time'. The optional argument ZONE defaults to the current time zone and its daylight savings time rules. If specified, it can be either a list (as you would get from `current-time-zone') or an integer (as you would get from `decode-time'). The specified zone is used without any further alteration for daylight savings time. If you pass more than seven arguments to `encode-time', the first six are used as SECONDS through YEAR, the last argument is used as ZONE, and the arguments in between are ignored. This feature makes it possible to use the elements of a list returned by `decode-time' as the arguments to `encode-time', like this: (apply 'encode-time (decode-time ...)) File: elisp, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface Timers for Delayed Execution ============================ You can set up a "timer" to call a function at a specified future time or after a certain length of idleness. Emacs cannot run a timer at any arbitrary point in a Lisp program; it can run them only when Emacs could accept output from a subprocess: namely, while waiting or inside certain primitive functions such as `sit-for' or `read-char' which *can* wait. Therefore, a timer's execution may be delayed if Emacs is busy. However, the time of execution is very precise if Emacs is idle. - Function: run-at-time TIME REPEAT FUNCTION &rest ARGS This function arranges to call FUNCTION with arguments ARGS at time TIME. The argument FUNCTION is a function to call later, and ARGS are the arguments to give it when it is called. The time TIME is specified as a string. Absolute times may be specified in a variety of formats; The form `HOUR:MIN:SEC TIMEZONE MONTH/DAY/YEAR', where all fields are numbers, works; the format that `current-time-string' returns is also allowed. To specify a relative time, use numbers followed by units. For example: `1 min' denotes 1 minute from now. `1 min 5 sec' denotes 65 seconds from now. `1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year' denotes exactly 103 months, 123 days, and 10862 seconds from now. If TIME is a number (integer or floating point), that specifies a relative time measured in seconds. The argument REPEAT specifies how often to repeat the call. If REPEAT is `nil', there are no repetitions; FUNCTION is called just once, at TIME. If REPEAT is a number, it specifies a repetition period measured in seconds. In any case, REPEAT has no effect on when *first* call takes place--TIME alone specifies that. The function `run-at-time' returns a timer value that identifies the particular scheduled future action. You can use this value to call `cancel-timer' (see below). - Macro: with-timeout (SECONDS TIMEOUT-FORMS...) BODY... Execute BODY, but give up after SECONDS seconds. If BODY finishes before the time is up, `with-timeout' returns the value of the last form in BODY. If, however, the execution of BODY is cut short by the timeout, then `with-timeout' executes all the TIMEOUT-FORMS and returns the value of the last of them. This macro works by set a timer to run after SECONDS seconds. If BODY finishes before that time, it cancels the timer. If the timer actually runs, it terminates execution of BODY, then executes TIMEOUT-FORMS. Since timers can run within a Lisp program only when the program calls a primitive that can wait, `with-timeout' cannot stop executing BODY while it is in the midst of a computation--only when it calls one of those primitives. So use `with-timeout' only with a BODY that waits for input, not one that does a long computation. The function `y-or-n-p-with-timeout' provides a simple way to use a timer to avoid waiting too long for an answer. *Note Yes-or-No Queries::. - Function: run-with-idle-timer SECS REPEAT FUNCTION &rest ARGS Set up a timer which runs when Emacs has been idle for SECS seconds. The value of SECS may be an integer or a floating point number. If REPEAT is `nil', the timer runs just once, the first time Emacs remains idle for a long enough time. More often REPEAT is non-`nil', which means to run the timer *each time* Emacs remains idle for SECS seconds. The function `run-with-idle-timer' returns a timer value which you can use in calling `cancel-timer' (see below). Emacs becomes "idle" when it starts waiting for user input, and it remains idle until the user provides some input. If a timer is set for five seconds of idleness, it runs approximately five seconds after Emacs first became idle. Even if its REPEAT is true, this timer will not run again as long as Emacs remains idle, because the duration of idleness will continue to increase and will not go down to five seconds again. Emacs can do various things while idle: garbage collect, autosave or handle data from a subprocess. But these interludes during idleness have little effect on idle timers. An idle timer set for 600 seconds will run when ten minutes have elapsed since the last user command was finished, even if subprocess output has been accepted thousands of times within those ten minutes, even if there have been garbage collections and autosaves. When the user supplies input, Emacs becomes non-idle while executing the input. Then it becomes idle again, and all the idle timers that are set up to repeat will subsequently run another time, one by one. - Function: cancel-timer TIMER Cancel the requested action for TIMER, which should be a value previously returned by `run-at-time' or `run-with-idle-timer'. This cancels the effect of that call to `run-at-time'; the arrival of the specified time will not cause anything special to happen. File: elisp, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface Terminal Input ============== This section describes functions and variables for recording or manipulating terminal input. See *Note Display::, for related functions. * Menu: * Input Modes:: Options for how input is processed. * Translating Input:: Low level conversion of some characters or events into others. * Recording Input:: Saving histories of recent or all input events. File: elisp, Node: Input Modes, Next: Translating Input, Up: Terminal Input Input Modes ----------- - Function: set-input-mode INTERRUPT FLOW META QUIT-CHAR This function sets the mode for reading keyboard input. If INTERRUPT is non-null, then Emacs uses input interrupts. If it is `nil', then it uses CBREAK mode. When Emacs communicates directly with X, it ignores this argument and uses interrupts if that is the way it knows how to communicate. If FLOW is non-`nil', then Emacs uses XON/XOFF (`C-q', `C-s') flow control for output to the terminal. This has no effect except in CBREAK mode. *Note Flow Control::. The default setting is system dependent. Some systems always use CBREAK mode regardless of what is specified. The argument META controls support for input character codes above 127. If META is `t', Emacs converts characters with the 8th bit set into Meta characters. If META is `nil', Emacs disregards the 8th bit; this is necessary when the terminal uses it as a parity bit. If META is neither `t' nor `nil', Emacs uses all 8 bits of input unchanged. This is good for terminals using European 8-bit character sets. If QUIT-CHAR is non-`nil', it specifies the character to use for quitting. Normally this character is `C-g'. *Note Quitting::. The `current-input-mode' function returns the input mode settings Emacs is currently using. - Function: current-input-mode This function returns current mode for reading keyboard input. It returns a list, corresponding to the arguments of `set-input-mode', of the form `(INTERRUPT FLOW META QUIT)' in which: INTERRUPT is non-`nil' when Emacs is using interrupt-driven input. If `nil', Emacs is using CBREAK mode. FLOW is non-`nil' if Emacs uses XON/XOFF (`C-q', `C-s') flow control for output to the terminal. This value has no effect unless INTERRUPT is non-`nil'. META is `t' if Emacs treats the eighth bit of input characters as the meta bit; `nil' means Emacs clears the eighth bit of every input character; any other value means Emacs uses all eight bits as the basic character code. QUIT is the character Emacs currently uses for quitting, usually `C-g'. File: elisp, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input Translating Input Events ------------------------ This section describes features for translating input events into other input events before they become part of key sequences. These features apply to each event in the order they are described here: each event is first modified according to `extra-keyboard-modifiers', then translated through `keyboard-translate-table' (if applicable). If it is being read as part of a key sequence, it is then added to the sequece being read; then subsequences containing it are checked first with `function-key-map' and then with `key-translation-map'. - Variable: extra-keyboard-modifiers This variable lets Lisp programs "press" the modifier keys on the keyboard. The value is a bit mask: 1 The SHIFT key. 2 The LOCK key. 4 The CTL key. 8 The META key. Each time the user types a keyboard key, it is altered as if the modifier keys specified in the bit mask were held down. When using X windows, the program can "press" any of the modifier keys in this way. Otherwise, only the CTL and META keys can be virtually pressed. - Variable: keyboard-translate-table This variable is the translate table for keyboard characters. It lets you reshuffle the keys on the keyboard without changing any command bindings. Its value must be a string or `nil'. If `keyboard-translate-table' is a string, then each character read from the keyboard is looked up in this string and the character in the string is used instead. If the string is of length N, character codes N and up are untranslated. In the example below, we set `keyboard-translate-table' to a string of 128 characters. Then we fill it in to swap the characters `C-s' and `C-\' and the characters `C-q' and `C-^'. Subsequently, typing `C-\' has all the usual effects of typing `C-s', and vice versa. (*Note Flow Control:: for more information on this subject.) (defun evade-flow-control () "Replace C-s with C-\ and C-q with C-^." (interactive) (let ((the-table (make-string 128 0))) (let ((i 0)) (while (< i 128) (aset the-table i i) (setq i (1+ i)))) ;; Swap `C-s' and `C-\'. (aset the-table ?\034 ?\^s) (aset the-table ?\^s ?\034) ;; Swap `C-q' and `C-^'. (aset the-table ?\036 ?\^q) (aset the-table ?\^q ?\036) (setq keyboard-translate-table the-table))) Note that this translation is the first thing that happens to a character after it is read from the terminal. Record-keeping features such as `recent-keys' and dribble files record the characters after translation. - Function: keyboard-translate FROM TO This function modifies `keyboard-translate-table' to translate character code FROM into character code TO. It creates or enlarges the translate table if necessary. The remaining translation features translate subsequences of key sequences being read. They are implemented in `read-key-sequence' and have no effect on `read-char'. - Variable: function-key-map This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal. This keymap uses the same data structure as other keymaps, but is used differently: it specifies translations to make while reading event sequences. If `function-key-map' "binds" a key sequence K to a vector V, then when K appears as a subsequence *anywhere* in a key sequence, it is replaced with the events in V. For example, VT100 terminals send `ESC O P' when the keypad PF1 key is pressed. Therefore, we want Emacs to translate that sequence of events into the single event `pf1'. We accomplish this by "binding" `ESC O P' to `[pf1]' in `function-key-map', when using a VT100. Thus, typing `C-c PF1' sends the character sequence `C-c ESC O P'; later the function `read-key-sequence' translates this back into `C-c PF1', which it returns as the vector `[?\C-c pf1]'. Entries in `function-key-map' are ignored if they conflict with bindings made in the minor mode, local, or global keymaps. The intent is that the character sequences that function keys send should not have command bindings in their own right. The value of `function-key-map' is usually set up automatically according to the terminal's Terminfo or Termcap entry, but sometimes those need help from terminal-specific Lisp files. Emacs comes with terminal-specific files for many common terminals; their main purpose is to make entries in `function-key-map' beyond those that can be deduced from Termcap and Terminfo. *Note Terminal-Specific::. Emacs versions 18 and earlier used totally different means of detecting the character sequences that represent function keys. - Variable: key-translation-map This variable is another keymap used just like `function-key-map' to translate input events into other events. It differs from `function-key-map' in two ways: * `key-translation-map' goes to work after `function-key-map' is finished; it receives the results of translation by `function-key-map'. * `key-translation-map' overrides actual key bindings. For example, if `C-x f' has a binding in `key-translation-map', that translation takes effect even though `C-x f' also has a key binding in the global map. The intent of `key-translation-map' is for users to map one character set to another, including ordinary characters normally bound to `self-insert-command'. You can use `function-key-map' or `key-translation-map' for more than simple aliases, by using a function, instead of a key sequence, as the "translation" of a key. Then this function is called to compute the translation of that key. The key translation function receives one argument, which is the prompt that was specified in `read-key-sequence'--or `nil' if the key sequence is being read by the editor command loop. In most cases you can ignore the prompt value. If the function reads input itself, it can have the effect of altering the event that follows. For example, here's how to define `C-c h' to turn the character that follows into a Hyper character: (defun hyperify (prompt) (let ((e (read-event))) (vector (if (numberp e) (logior (lsh 1 20) e) (if (memq 'hyper (event-modifiers e)) e (add-event-modifier "H-" e)))))) (defun add-event-modifier (string e) (let ((symbol (if (symbolp e) e (car e)))) (setq symbol (intern (concat string (symbol-name symbol)))) (if (symbolp e) symbol (cons symbol (cdr e))))) (define-key function-key-map "\C-ch" 'hyperify) The `iso-transl' library uses this feature to provide a way of inputting non-ASCII Latin-1 characters. File: elisp, Node: Recording Input, Prev: Translating Input, Up: Terminal Input Recording Input --------------- - Function: recent-keys This function returns a vector containing the last 100 input events from the keyboard or mouse. All input events are included, whether or not they were used as parts of key sequences. Thus, you always get the last 100 inputs, not counting keyboard macros. (Events from keyboard macros are excluded because they are less interesting for debugging; it should be enough to see the events that invoked the macros.) - Command: open-dribble-file FILENAME This function opens a "dribble file" named FILENAME. When a dribble file is open, each input event from the keyboard or mouse (but not those from keyboard macros) is written in that file. A non-character event is expressed using its printed representation surrounded by `<...>'. You close the dribble file by calling this function with an argument of `nil'. This function is normally used to record the input necessary to trigger an Emacs bug, for the sake of a bug report. (open-dribble-file "~/dribble") => nil See also the `open-termscript' function (*note Terminal Output::.). File: elisp, Node: Terminal Output, Next: Special Keysyms, Prev: Terminal Input, Up: System Interface Terminal Output =============== The terminal output functions send output to the terminal or keep track of output sent to the terminal. The variable `baud-rate' tells you what Emacs thinks is the output speed of the terminal. - Variable: baud-rate This variable's value is the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations such as padding. It also affects decisions about whether to scroll part of the screen or repaint--even when using a window system. (We designed it this way despite the fact that a window system has no true "output speed", to give you a way to tune these decisions.) The value is measured in baud. If you are running across a network, and different parts of the network work at different baud rates, the value returned by Emacs may be different from the value used by your local terminal. Some network protocols communicate the local terminal speed to the remote machine, so that Emacs and other programs can get the proper value, but others do not. If Emacs has the wrong value, it makes decisions that are less than optimal. To fix the problem, set `baud-rate'. - Function: baud-rate This function returns the value of the variable `baud-rate'. In Emacs versions 18 and earlier, this was the only way to find out the terminal speed. - Function: send-string-to-terminal STRING This function sends STRING to the terminal without alteration. Control characters in STRING have terminal-dependent effects. One use of this function is to define function keys on terminals that have downloadable function key definitions. For example, this is how on certain terminals to define function key 4 to move forward four characters (by transmitting the characters `C-u C-f' to the computer): (send-string-to-terminal "\eF4\^U\^F") => nil - Command: open-termscript FILENAME This function is used to open a "termscript file" that will record all the characters sent by Emacs to the terminal. It returns `nil'. Termscript files are useful for investigating problems where Emacs garbles the screen, problems that are due to incorrect Termcap entries or to undesirable settings of terminal options more often than to actual Emacs bugs. Once you are certain which characters were actually output, you can determine reliably whether they correspond to the Termcap specifications in use. See also `open-dribble-file' in *Note Terminal Input::. (open-termscript "../junk/termscript") => nil File: elisp, Node: Special Keysyms, Next: Flow Control, Prev: Terminal Output, Up: System Interface System-Specific X11 Keysyms =========================== To define system-specific X11 keysyms, set the variable `system-key-alist'. - Variable: system-key-alist This variable's value should be an alist with one element for each system-specific keysym. An element has this form: `(CODE . SYMBOL)', where CODE is the numeric keysym code (not including the "vendor specific" bit, 1 << 28), and SYMBOL is the name for the function key. For example `(168 . mute-acute)' defines a system-specific key used by HP X servers whose numeric code is (1 << 28) + 168. It is not a problem if the alist defines keysyms for other X servers, as long as they don't conflict with the ones used by the X server actually in use. The variable is always local to the current X terminal and cannot be buffer-local. *Note Multiple Displays::. File: elisp, Node: Flow Control, Next: Batch Mode, Prev: Special Keysyms, Up: System Interface Flow Control ============ This section attempts to answer the question "Why does Emacs choose to use flow-control characters in its command character set?" For a second view on this issue, read the comments on flow control in the `emacs/INSTALL' file from the distribution; for help with Termcap entries and DEC terminal concentrators, see `emacs/etc/TERMS'. At one time, most terminals did not need flow control, and none used `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and `C-q' as command characters was uncontroversial. Emacs, for economy of keystrokes and portability, used nearly all the ASCII control characters, with mnemonic meanings when possible; thus, `C-s' for search and `C-q' for quote. Later, some terminals were introduced which required these characters for flow control. They were not very good terminals for full-screen editing, so Emacs maintainers did not pay attention. In later years, flow control with `C-s' and `C-q' became widespread among terminals, but by this time it was usually an option. And the majority of users, who can turn flow control off, were unwilling to switch to less mnemonic key bindings for the sake of flow control. So which usage is "right", Emacs's or that of some terminal and concentrator manufacturers? This question has no simple answer. One reason why we are reluctant to cater to the problems caused by `C-s' and `C-q' is that they are gratuitous. There are other techniques (albeit less common in practice) for flow control that preserve transparency of the character stream. Note also that their use for flow control is not an official standard. Interestingly, on the model 33 teletype with a paper tape punch (which is very old), `C-s' and `C-q' were sent by the computer to turn the punch on and off! As X servers and other window systems replace character-only terminals, this problem is gradually being cured. For the mean time, Emacs provides a convenient way of enabling flow control if you want it: call the function `enable-flow-control'. - Function: enable-flow-control This function enables use of `C-s' and `C-q' for output flow control, and provides the characters `C-\' and `C-^' as aliases for them using `keyboard-translate-table' (*note Translating Input::.). You can use the function `enable-flow-control-on' in your `.emacs' file to enable flow control automatically on certain terminal types. - Function: enable-flow-control-on &rest TERMTYPES This function enables flow control, and the aliases `C-\' and `C-^', if the terminal type is one of TERMTYPES. For example: (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") Here is how `enable-flow-control' does its job: 1. It sets CBREAK mode for terminal input, and tells the operating system to handle flow control, with `(set-input-mode nil t)'. 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^' into `C-s' and `C-q'. Except at its very lowest level, Emacs never knows that the characters typed were anything but `C-s' and `C-q', so you can in effect type them as `C-\' and `C-^' even when they are input for other commands. *Note Translating Input::. If the terminal is the source of the flow control characters, then once you enable kernel flow control handling, you probably can make do with less padding than normal for that terminal. You can reduce the amount of padding by customizing the Termcap entry. You can also reduce it by setting `baud-rate' to a smaller value so that Emacs uses a smaller speed when calculating the padding needed. *Note Terminal Output::. File: elisp, Node: Batch Mode, Prev: Flow Control, Up: System Interface Batch Mode ========== The command line option `-batch' causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with `-l FILE', which loads the library named FILE, and `-f FUNCTION', which calls FUNCTION with no arguments. Any Lisp program output that would normally go to the echo area, either using `message' or using `prin1', etc., with `t' as the stream, goes instead to Emacs's standard error descriptor when in batch mode. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.) - Variable: noninteractive This variable is non-`nil' when Emacs is running in batch mode. File: elisp, Node: Display, Next: Calendar, Prev: System Interface, Up: Top Emacs Display ************* This chapter describes a number of features related to the display that Emacs presents to the user. * Menu: * Refresh Screen:: Clearing the screen and redrawing everything on it. * Screen Size:: How big is the Emacs screen. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. * Invisible Text:: Hiding part of the buffer text. * Selective Display:: Hiding part of the buffer text (the old way). * Overlay Arrow:: Display of an arrow to indicate position. * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. * Faces:: A face defines a graphics appearance: font, color, etc. * Blinking:: How Emacs shows the matching open parenthesis. * Inverse Video:: Specifying how the screen looks. * Usual Display:: The usual conventions for displaying nonprinting chars. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used. File: elisp, Node: Refresh Screen, Next: Screen Size, Up: Display Refreshing the Screen ===================== The function `redraw-frame' redisplays the entire contents of a given frame. *Note Frames::. - Function: redraw-frame FRAME This function clears and redisplays frame FRAME. Even more powerful is `redraw-display': - Command: redraw-display This function clears and redisplays all visible frames. Processing user input takes absolute priority over redisplay. If you call these functions when input is available, they do nothing immediately, but a full redisplay does happen eventually--after all the input has been processed. Normally, suspending and resuming Emacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption. - Variable: no-redraw-on-reenter This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-`nil' means yes, `nil' means no. File: elisp, Node: Screen Size, Next: Truncation, Prev: Refresh Screen, Up: Display Screen Size =========== The screen size functions access or specify the height or width of the terminal. When you are using multiple frames, they apply to the selected frame (*note Frames::.). - Function: screen-height This function returns the number of lines on the screen that are available for display. (screen-height) => 50 - Function: screen-width This function returns the number of columns on the screen that are available for display. (screen-width) => 80 - Function: set-screen-height LINES &optional NOT-ACTUAL-SIZE This function declares that the terminal can display LINES lines. The sizes of existing windows are altered proportionally to fit. If NOT-ACTUAL-SIZE is non-`nil', then Emacs displays LINES lines of output, but does not change its value for the actual height of the screen. (Knowing the correct actual size may be necessary for correct cursor positioning.) Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. If LINES is different from what it was previously, then the entire screen is cleared and redisplayed using the new size. This function returns `nil'. - Function: set-screen-width COLUMNS &optional NOT-ACTUAL-SIZE This function declares that the terminal can display COLUMNS columns. The details are as in `set-screen-height'. File: elisp, Node: Truncation, Next: The Echo Area, Prev: Screen Size, Up: Display Truncation ========== When a line of text extends beyond the right edge of a window, the line can either be continued on the next screen line, or truncated to one screen line. The additional screen lines used to display a long text line are called "continuation" lines. Normally, a `$' in the rightmost column of the window indicates truncation; a `\' on the rightmost column indicates a line that "wraps" or is continued onto the next line. (The display table can specify alternative indicators; see *Note Display Tables::.) Note that continuation is different from filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. *Note Filling::. - User Option: truncate-lines This buffer-local variable controls how Emacs displays lines that extend beyond the right edge of the window. The default is `nil', which specifies continuation. If the value is non-`nil', then these lines are truncated. If the variable `truncate-partial-width-windows' is non-`nil', then truncation is always used for side-by-side windows (within one frame) regardless of the value of `truncate-lines'. - User Option: default-truncate-lines This variable is the default value for `truncate-lines', for buffers that do not have local values for it. - User Option: truncate-partial-width-windows This variable controls display of lines that extend beyond the right edge of the window, in side-by-side windows (*note Splitting Windows::.). If it is non-`nil', these lines are truncated; otherwise, `truncate-lines' says what to do with them. You can override the images that indicate continuation or truncation with the display table; see *Note Display Tables::. If your buffer contains *very* long lines, and you use continuation to display them, just thinking about them can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set `cache-long-line-scans' to `t'. - Variable: cache-long-line-scans If this variable is non-`nil', various indentation and motion functions, and Emacs redisplay, cache the results of scanning the buffer, and consult the cache to avoid rescanning regions of the buffer unless they are modified. Turning on the cache slows down processing of short lines somewhat. This variable is automatically local in every buffer. File: elisp, Node: The Echo Area, Next: Invisible Text, Prev: Truncation, Up: Display The Echo Area ============= The "echo area" is used for displaying messages made with the `message' primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The `GNU Emacs Manual' specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (*note The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo area; see *Note Errors::. You can write output in the echo area by using the Lisp printing functions with `t' as the stream (*note Output Functions::.), or as follows: - Function: message STRING &rest ARGUMENTS This function displays a one-line message in the echo area. The argument STRING is similar to a C language `printf' control string. See `format' in *Note String Conversion::, for the details on the conversion specifications. `message' returns the constructed string. In batch mode, `message' prints the message text on the standard error stream, followed by a newline. If STRING is `nil', `message' clears the echo area. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately. (message "Minibuffer depth is %d." (minibuffer-depth)) -| Minibuffer depth is 0. => "Minibuffer depth is 0." ---------- Echo Area ---------- Minibuffer depth is 0. ---------- Echo Area ---------- Almost all the messages displayed in the echo area are also recorded in the `*Messages*' buffer. - User Option: message-log-max This variable specifies how many lines to keep in the `*Messages*' buffer. The value `t' means there is no limit on how many lines to keep. The value `nil' disables message logging entirely. Here's how to display a message and prevent it from being logged: (let (message-log-max) (message ...)) - Variable: echo-keystrokes This variable determines how much time should elapse before command characters echo. Its value must be an integer, which specifies the number of seconds to wait before echoing. If the user types a prefix key (such as `C-x') and then delays this many seconds before continuing, the prefix key is echoed in the echo area. Any subsequent characters in the same command will be echoed as well. If the value is zero, then command input is not echoed. - Variable: cursor-in-echo-area This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-`nil', then the cursor appears at the end of the message. Otherwise, the cursor appears at point--not in the echo area at all. The value is normally `nil'; Lisp programs bind it to `t' for brief periods of time. File: elisp, Node: Invisible Text, Next: Selective Display, Prev: The Echo Area, Up: Display Invisible Text ============== You can make characters "invisible", so that they do not appear on the screen, with the `invisible' property. This can be either a text property or a property of an overlay. In the simplest case, any non-`nil' `invisible' property makes a character invisible. This is the default case--if you don't alter the default value of `buffer-invisibility-spec', this is how the `invisibility' property works. This feature is much like selective display (*note Selective Display::.), but more general and cleaner. More generally, you can use the variable `buffer-invisibility-spec' to control which values of the `invisible' property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different `invisible' values, and subsequently make various subsets visible or invisible by changing the value of `buffer-invisibility-spec'. Controlling visibility with `buffer-invisibility-spec' is especially useful in a program to display the list of entries in a data base. It permits the implementation of convenient filtering commands to view just a part of the entries in the data base. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change. - Variable: buffer-invisibility-spec This variable specifies which kinds of `invisible' properties actually make a character invisible. `t' A character is invisible if its `invisible' property is non-`nil'. This is the default. a list Each element of the list makes certain characters invisible. Ultimately, a character is invisible if any of the elements of this list applies to it. The list can have two kinds of elements: `ATOM' A character is invisible if its `invisible' propery value is ATOM or if it is a list with ATOM as a member. `(ATOM . t)' A character is invisible if its `invisible' propery value is ATOM or if it is a list with ATOM as a member. Moreover, if this character is at the end of a line and is followed by a visible newline, it displays an ellipsis. Ordinarily, commands that operate on text or move point do not care whether the text is invisible. The user-level line motion commands explicitly ignore invisible newlines if `line-move-ignore-invisible' is non-`nil', but only because they are explicitly programmed to do so. File: elisp, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display Selective Display ================= "Selective display" is a pair of features that hide certain lines on the screen. The first variant, explicit selective display, is designed for use in a Lisp program. The program controls which lines are hidden by altering the text. Outline mode has traditionally used this variant. It has been partially replaced by the invisible text feature (*note Invisible Text::.); there is a new version of Outline mode which uses that instead. In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a user-level feature. The way you control explicit selective display is by replacing a newline (control-j) with a carriage return (control-m). The text that was formerly a line following that newline is now invisible. Strictly speaking, it is temporarily no longer a line at all, since only newlines can separate lines; it is now part of the previous line. Selective display does not directly affect editing commands. For example, `C-f' (`forward-char') moves point unhesitatingly into invisible text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, `next-line' skips invisible lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that make parts of the text visible or invisible. When you write a selectively displayed buffer into a file, all the control-m's are output as newlines. This means that when you next read in the file, it looks OK, with nothing invisible. The selective display effect is seen only within Emacs. - Variable: selective-display This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made invisible. * If the value of `selective-display' is `t', then any portion of a line that follows a control-m is not displayed. * If the value of `selective-display' is a positive integer, then lines that start with more than that many columns of indentation are not displayed. When some portion of a buffer is invisible, the vertical movement commands operate as if that portion did not exist, allowing a single `next-line' command to skip any number of invisible lines. However, character movement commands (such as `forward-char') do not skip the invisible portion, and it is possible (if tricky) to insert or delete text in an invisible portion. In the examples below, we show the *display appearance* of the buffer `foo', which changes with the value of `selective-display'. The *contents* of the buffer do not change. (setq selective-display nil) => nil ---------- Buffer: foo ---------- 1 on this column 2on this column 3n this column 3n this column 2on this column 1 on this column ---------- Buffer: foo ---------- (setq selective-display 2) => 2 ---------- Buffer: foo ---------- 1 on this column 2on this column 2on this column 1 on this column ---------- Buffer: foo ---------- - Variable: selective-display-ellipses If this buffer-local variable is non-`nil', then Emacs displays `...' at the end of a line that is followed by invisible text. This example is a continuation of the previous one. (setq selective-display-ellipses t) => t ---------- Buffer: foo ---------- 1 on this column 2on this column ... 2on this column 1 on this column ---------- Buffer: foo ---------- You can use a display table to substitute other text for the ellipsis (`...'). *Note Display Tables::. File: elisp, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display The Overlay Arrow ================= The "overlay arrow" is useful for directing the user's attention to a particular line in a buffer. For example, in the modes used for interface to debuggers, the overlay arrow indicates the line of code about to be executed. - Variable: overlay-arrow-string This variable holds the string to display to call attention to a particular line, or `nil' if the arrow feature is not in use. - Variable: overlay-arrow-position This variable holds a marker that indicates where to display the overlay arrow. It should point at the beginning of a line. The arrow text appears at the beginning of that line, overlaying any text that would otherwise appear. Since the arrow is usually short, and the line usually begins with indentation, normally nothing significant is overwritten. The overlay string is displayed only in the buffer that this marker points into. Thus, only one buffer can have an overlay arrow at any given time. You can do the same job by creating an overlay with a `before-string' property. *Note Overlay Properties::.